home *** CD-ROM | disk | FTP | other *** search
/ TOS Silver 2000 / TOS Silver 2000.iso / Tools / RSM31D / modules / ovl_dev / overlay.txt next >
Encoding:
Text File  |  1999-10-24  |  6.0 KB  |  190 lines
  1. Overlays ab ResourceMaster v3.0
  2. -------------------------------
  3.  
  4. Armin Diedering
  5. letzte Änderung: 21.1.99
  6. Tabulatorweite: 3
  7.  
  8.  
  9. 1. Was sind ResourceMaster-Overlays ?
  10. =====================================
  11.  
  12. ResourceMaster unterstützt ab Version 3.0 Overlays. Ein Overlay wird beim 
  13. Programmstart aus dem "modules"-Ordner geladen.
  14.  
  15.  
  16. 2. Wozu ResourceMaster-Overlays ?
  17. =================================
  18.  
  19. Overlays können das Zeichnen der Objekte im Dialog- bzw- Menü-Editor 
  20. übernehmen. Dadurch können die Objekte im Editor schon so aussehen, wie 
  21. später im Programm (FlyDials usw.)
  22.  
  23.  
  24. 3. Wie Programmiere ich ein Overlay ?
  25. =====================================
  26.  
  27. 3.1 Was muß das Overlay machen?
  28. ===============================
  29.  
  30. Ein Overlay ist ein normales TOS-Programm und wird mit einer Kommandozeile 
  31. gestartet. Diese Kommandozeile hat immer eine Länge von 14 Zeichen. Sie muß 
  32. mit "RSMOVL" beginnen. Das sind schon mal 6 Zeichen. Die restlichen 8 
  33. Zeichen stellen eine 32-bit-HEX-Zahl dar (dabei gilt: 'A'=0, 'B'=1 ... 
  34. 'J'=9, 'K'=a ... 'O'=e und 'P'=f).
  35.  
  36. Diese HEX-Zahl zeigt auf einen OVL2RSM-Zeiger (OVL2RSM**). Einzige Aufgabe 
  37. des StartUp-Codes ist es, die Adresse der eigenen "OVL2RSM"-Structur dort 
  38. einzutragen. Ist alles glatt gegangen, dann beendet sich das Overlay mit 
  39. Pterm(0). Ist ein Fehler aufgetreten, dann muß es sich mit Pterm(1) beenden.
  40.  
  41. Man sollte folgenden StartUp-Code verwendet: 
  42.  
  43. ------------Schnipp-----------
  44. extern OVL2RSM* Overlay;
  45.  
  46. WORD OverlayStartUp(BASEPAGE* BasePage)
  47. {
  48.     WORD Ret = 1;
  49.  
  50.     if(BasePage->p_cmdlin[0] == 14)    /* immer 14 Byte lang */
  51.     {
  52.         if(!strncmp(&BasePage->p_cmdlin[1], "RSMOVL", 6))
  53.         {
  54.             LONG Adr        = 0;
  55.             char* Pos    = &BasePage->p_cmdlin[7];
  56.             WORD i;
  57.  
  58.             for(i=0; i<8; i++)
  59.             {
  60.                 Adr <<= 4;
  61.                 Adr |= *Pos++ - 'A';            /* 'A'=0 usw. */
  62.             }
  63.             *((OVL2RSM**)Adr)    = &Overlay;    /* Adresse der Struktur eintragen */
  64.             Ret = 0;                                /* alles OK zurückgeben           */
  65.         }
  66.     }
  67.     Pterm(Ret);
  68. }
  69. ------------Schnapp-----------
  70.  
  71. so jetzt kommt noch die Overlay-to-ResourceMaster-Structur:
  72.  
  73. ------------Schnipp-----------
  74. typedef struct
  75. {
  76.     LONG    Magic;                    /* 0x4f424a43 'OBJC'        */
  77.     WORD    Protokoll;                /* zur Zeit NULL            */
  78.     LONG    ID;                        /* Anhand der ID werden     */
  79.                                         /* Overlays unterschieden   */
  80.     WORD    Version;                    /* vom Overlay abhängig     */
  81.     char    Name[32];                /* vom Overlay abhängig     */
  82.     char    Copyright[32];            /* vom Overlay abhängig     */
  83.  
  84.     WORD    (*Init)(const char* FileName, UWORD* Global, RSM2OVL* RsmOvl);
  85.     void    (*Exit)();
  86.  
  87.     WORD    (*Draw)(OBJECT* Objc, LONG* Clip);
  88.  
  89. } OVL2RSM;
  90. ------------Schnapp-----------
  91.  
  92. MagiC:       muß immer 0x4f424a43 ('OBJC') sein
  93. ------
  94.  
  95. Protokoll:   Sollte die OVL2RSM-Struktur einmal erweitert werden, dann
  96. ----------   können diese Erweiterungen anhand der Protokollversion erkannt 
  97.              werden.
  98.  
  99.  
  100. ID:          Jedes Overlay muß sich durch seine ID eindeutig identifizieren
  101. ---          lassen. Irgend wann einmal soll RSM auch mehrere Overlays 
  102.              gleichzeitig unterstützen. Damit für jede Resource das richtige 
  103.              Overlay aktiviert wird, speichert RSM schon heute die ID des 
  104.              Overlays in die *.rsm-Datei.
  105.              
  106.              Ich führe eine Liste aller vergebener IDs. Wenn ein Autor ein 
  107.              Overlay veröffentlichen möchte, dann sollte er mir die geplante 
  108.              ID mitteilen.
  109.  
  110. Version:     Haxadezimal codierte Version des Overlays z.B. 0101 für v1.01. 
  111. --------
  112.  
  113. Name:        Name des Overlays (max 32 Zeichen inkl. 0-Byte)
  114. -----
  115.  
  116. Copyright:   Copyright des Overlays (max 32 Zeichen inkl. 0-Byte)
  117. ----------
  118.  
  119. WORD Init(const char* FileName, UWORD* Global, RSM2OVL* RsmOvl);
  120. ----------------------------------------------------------------
  121.  
  122. FileName: Kompletter Name incl. Pfad des Overlays. Kann z.B. dazu benutzt zu 
  123.           werden, um eine *.inf oder *.cnf zu finden und zu laden.
  124. Global:   Das Global-Feld von RSM. Das Overlay darf kein appl_init und schon 
  125.           gar kein appl_exit machen. Das Global-Feld kann dazu benutzt 
  126.           werden um AES-Funktionen (auch ohne appl_init) aufzurufen. Das 
  127.           Overlay darf aber das Global-Felds nicht direkt benutzen.
  128.           <<<<<<<<<< Es darf nur eine Kopie verwenden >>>>>>>>>>
  129. RsmOvl:   Über die RSM2OVL-Struktur kann der ResourceMaster dem Overlay 
  130.           diverse Funktionen und Informationen zur Verfügung stellen.
  131.           
  132.   Die Init Funktion ist jetzt dazu da, um das Overlay zu
  133.   initialisieren. Es kann Speicher angefordert werden usw.
  134.  
  135. Ergebnis: 0=>OK , !=0 => Fehler
  136.  
  137.  
  138.  
  139. void Exit();
  140. ------------
  141.  
  142.   Dient der De-Initialisation (Speicher freigeben usw.)
  143.  
  144.  
  145.  
  146. WORD Draw(OBJECT* Objc, LONG* Clip);
  147. -------------------------------------
  148.  
  149. Objc: Das Objekt als Baum (ob_head, _tail und _next = -1)
  150. Clip: Ein Zeiger auf 4 LONG-Werte (x,y,w,h) für das Cliping.
  151.                        ====
  152. Das Overlay muß entscheiden, ob es das Objekt Zeichnen möchte oder nicht.
  153.  
  154. Ergebnis: 0 => Ich habe das Objekt selber gezeichnet
  155.           1 => Ich habe das Objekt nicht gezeichnet;
  156.                RSM soll das Objekt zeichnen
  157.  
  158.  
  159. 3.2 Was macht der ResourceMaster ?
  160. ==================================
  161.  
  162. Der ResourceMaster stellt dem Overlay die RSM2OVL-Struktur zur Verfügung.
  163.  
  164. ------------Schnipp-----------
  165. typedef struct
  166. {
  167.     WORD        Protokoll;    /* zur Zeit NULL          */
  168. } RSM2OVL;
  169. ------------Schnapp-----------
  170.  
  171. Protokoll: Gibt Auskunft darüber, welcher Erweiterungen Verfügbar sind.
  172. ----------
  173.  
  174. 4. Kontakt
  175. ==========
  176.  
  177. Wer ein Overlay programmiert muß dem Overlay eine eindeutige ID geben. Um 
  178. Doppelbelegungen zu vermeiden, führe ich eine Liste der IDs.
  179. Wer ein Overlay plant sollte mir die geplante ID mitteilen und auf meine 
  180. Rückmeldung warten. Wenn die ID noch frei ist, dann wird sie in der Liste 
  181. aufgenommen.
  182. Die Mitteilung der geplanten Overlay-ID sollte nur per e-Mail erfolgen.
  183.  
  184.      Armin@Diedering.de
  185.  
  186. Außerdem wird man die Liste auch auf meiner Homepage finden
  187.  
  188.      http://www.Diedering.de
  189.  
  190.